package com.spoorle.perf.iface;

import java.util.List;
/**
 * <p>Probe captures statistical performance data.</p>
 * <p>Each instance is bound to certain class via factory create method. Probe object manages common properties
 * of performance capture such as enabling or disabling the process.</p><p>Probe object provides also an access to
 * the results of the statistics captured via get methods.</p>
 * <p>When one needs textual representation of statistics spool method should be used.</p>
 * @author Maciej Grula <a href="mailto:maciej.grula@gmail.com">maciej.grula@gmail.com</a>
 *
 */
public interface Probe {
	/**
	 * When probe is enabled then execution data for new events are gathered.
	 * Otherwise start operation events are skipped. By default probe is enabled
	 * <br/>
	 * <em><b>Warning!</b> This setting affects all probes not only that particular on which
	 * this method was invoked.</em>
	 * 
	 * @return
	 */
	public abstract boolean isEnabled();
	/**
	 * Enables performance measuring. May influence 
	 * application stability.
	 * <br/>
	 * <em><b>Warning!</b> This setting affects all probes not only that particular on which
	 * this method was invoked.</em>
	 */
	public abstract void enable();
	/**
	 * Disables performance measuring. However, statistics data
	 * is not released as another call to enable() is possible.
	 * 
	 * When one needs to release all resources and zero statistics then 
	 * release() method should be used
	 * 
	 * <br/>
	 * <em><b>Warning!</b> This setting affects all probes not only that particular on which
	 * this method was invoked.</em>
	 * 
	 * @see Probe#release()
	 */
	public abstract void disable();
	/**
	 * Starts measurement for given user operation. Should be always followed by 
	 * stop method call.
	 * @param operation textual representation of user operation
	 */
	public abstract void start(String operation);
	
	/**
	 * Stops measurement for given user operation. Statistics are updated.
	 * When there was no preceeding start method invocation then nothing happens.
	 * @param operation textual representation of user operation
	 */
	public abstract void stop(String operation);
	
	/**
	 * Retrieves statistics data in default text format.
	 * @return
	 */
	public abstract String spool();
	/**
	 * Up to now performance statistics. May be null if there is no data available.
	 * @return
	 */
	public abstract List<Statistics> getStatistics();
	/**
	 * Up to now performance statistics for given operation in class.
	 * @param operation 
	 * @param clazz
	 * @return
	 */
	public abstract Statistics getStatistics(String operation, Class clazz);
	/**
	 * Zeros statistics and releases all resources consumed by probe. Probe
	 * is disabled by default after this method call so one needs to manually enable it. 
	 */
	public abstract void release();
}
